home *** CD-ROM | disk | FTP | other *** search
/ OpenGL Superbible (2nd Edition) / OpenGL SuperBible e2.iso / tools / GLUT-3.7 / README.fortran < prev    next >
Encoding:
Text File  |  1998-08-12  |  6.7 KB  |  170 lines
  1. GLUT Fortran users,
  2.  
  3. BUILD INSTRUCTIONS
  4. ===================
  5.  
  6. To build the GLUT Fortran API, do the following:
  7.  
  8.   1)  Make sure you are running IRIX 5.3, 6.1, or 6.2 or higher.
  9.  
  10.   2)  Make sure you have Fortran compilers and OpenGL Fortran
  11.       libraries installed (make sure you have the right support
  12.       installed for the "object style" you wish to build).
  13.  
  14.       The following Fortran subsystems are particularly important
  15.       to have installed:
  16.  
  17.         ftn77_dev.sw.util  -- utiles for building Fortran to C bindings
  18.     gl_dev.sw.fortran  -- OpenGL Fortran binding libraries
  19.  
  20.   3)  Run "mkmkfiles.sgi" in this directory.
  21.  
  22.   4)  Make sure you have built the "lib/glut" and "lib/fglut"
  23.       directories:
  24.  
  25.       (cd lib/glut; make)
  26.       (cd lib/fglut; make)
  27.  
  28.   5)  Change to one of the GLUT Fortran library directories,
  29.       depending on what "object style" you wish to build:
  30.  
  31.       O32 (old 32-bit ABI) - "cd lib/fglut"
  32.       N64 (new 64-bit ABI) - "cd lib/fglut.n64"   (IRIX 6.1 & 6.2 only)
  33.       N32 (new 32-bit ABI) - "cd lib/fglut.n32"   (IRIX 6.2 only)
  34.  
  35.       (If you are building a given "object style", make sure you
  36.       build the accompanying GLUT library implementation.  See
  37.       README.irix6)
  38.  
  39.   6)  Execute "make" in the directory.
  40.  
  41. NOTES
  42. ======
  43.  
  44. All GLUT functionality is available through the GLUT Fortran API.
  45.  
  46. A number of example GLUT Fortran examples are built in the directory as
  47. examples of how to write GLUT Fortran programs.
  48.  
  49. There are a number of caveats to using the GLUT Fortran API:
  50.  
  51.   o  The GLUT Fortran API is not built by default.
  52.  
  53.      See the build instructions above.  You will need the IRIX Fortran
  54.      development option installed.
  55.  
  56.   o  The implementation of the GLUT Fortran API is probably only useful
  57.      to IRIX users because the generation of Fortran-to-C wrappers is
  58.      inherently dependent on vendor-dependent calling convention
  59.      dependencies.
  60.  
  61.   o  The IRIX GLUT Fortran API is implemented as a set of wrappers to
  62.      to the GLUT C implementation.  As such, there is a very slight
  63.      overhead to calling OpenGL routine through the GLUT Fortran
  64.      binding (this applies to the OpenGL Fortran wrapper routines as
  65.      well).
  66.  
  67.   o  The ARB's official OpenGL Fortran API prefixes every routine and
  68.      constant with the letter F.  The justification was to avoid name
  69.      space collisions with the C names.  Nearly all modern Fortran
  70.      compilers avoid these name space clashes via other means (underbar
  71.      suffixing of Fortran routines is used by most Unix Fortran
  72.      compilers).
  73.  
  74.      The GLUT Fortran API does _not_ use such prefixing conventions
  75.      because of the documentation and coding confusion introduced by
  76.      such prefixes.  Bending over backwards to support anachronistic
  77.      compliers does not justify this confusion.
  78.  
  79.      While the official OpenGL Fortran API, prefixes both routine and
  80.      constant names, there is no technical justification for prefixing
  81.      constant names.  In practice, it creates a reasonable amount of
  82.      coding and documentation confusion (the confusion is heightened by
  83.      Fortran's default implicit variable initialization so you don't
  84.      realize the lack of a constant prefix until run-time) and pushes
  85.      names one character towards identifier limits.
  86.  
  87.      The GLUT distribution supplies its own version of "GL/fgl.h" and
  88.      "GL/fglu.h" which does not F-prefix constants.  GLUT users are
  89.      encouraged to not use the F-prefixed constants.  (The GLUT
  90.      supplied "GL/fgl.h" also works around problems discussed in the
  91.      next bullet.)
  92.  
  93.      Perhaps the OpenGL ARB will reconsider the F-prefix or (as an
  94.      unfortunate compromise) support both F prefixed and non F prefixed
  95.      constant names.
  96.  
  97.   o  A OpenGL Fortran API implementation was released with IRIX 5.3
  98.      (it was not previously available in IRIX).  While the Fortran
  99.      wrappers work, there are a number of difficulties with using the
  100.      IRIX 5.3 OpenGL Fortran bindings:
  101.  
  102.        +  Make sure you have the "Fortran 77 OpenGL Graphic Library"
  103.       subsystem installed.  Its name is:  ftn_dev.sw.opengl
  104.  
  105.        +  The OpenGL Fortran man pages incorrectly document a number of
  106.       calls taking REAL*4 (real) parameters when they in fact
  107.       require REAL*8 (double precision) parameters.  An example is
  108.       fglviewport.  Any OpenGL (or GLU) routine that takes double's
  109.       as parameters in the C API, takes REAL*8's in the Fortran
  110.       API.  Be very careful to use the dble intrinsic whenever
  111.       passing non-REAL*8 values to such routines!
  112.  
  113.        +  The OpenGL Fortran man pages also do not add the F-prefixes
  114.       to constants discussed in the man pages.  Because GLUT
  115.       supplies a "GL/fgl.h" without F-prefixes, this should be a
  116.       "good thing."
  117.  
  118.        +  The "GL/fgl.h" header file describing the OpenGL Fortran API
  119.       contains identifiers over 32 characters long.  While the MIPS
  120.       Fortran compiler should treat this as a soft warning and
  121.       truncate the identifiers to 32 characters, the compiler
  122.       generates a fatal error.  For this reason, the "GL/fgl.h" in
  123.       this distribution has truncated by hand the "GL/fgl.h"
  124.       identifiers over 32 characters to 32 characters.
  125.  
  126.   o  IRIX 6.2's OpenGL Fortran binding was quite bungled and is
  127.      basically unusable.
  128.      
  129.      A workaround for this problem is to compile your OpenGL Fortran
  130.      programs with the compiler option "-Wl,-ignore_unresolved".  This
  131.      tells the compiler to ignore unresolved symbols.
  132.  
  133.      Then, when you run the OpenGL Fortran binaries, tell the run-time
  134.      linker (rld) to ignore unresolved symbols like this:
  135.  
  136.        setenv _RLD_ARGS -ignore_unresolved
  137.  
  138.      SGI patches 1892 (IRIX 6.3 and 6.4 OpenGL Fortran bindings) and
  139.      2360 (IRIX 6.2 OpenGL Fortran bindings) should fix problems in the
  140.      OpenGL Fortran binding library.
  141.  
  142.   o  Because GLUT fonts are compiled into programs and programs
  143.      should only have the fonts compiled into them that they use,
  144.      GLUT font names like GLUT_BITMAP_TIMES_ROMAN_24 are really
  145.      symbols so the linker should only pull in used fonts.
  146.      Unfortunately, if a data symbol is declared EXTERNAL, the
  147.      IRIX Fortran compiler pulls in the symbol whether the symbol
  148.      is used or not.  For this reason, "GL/fglut.h" does not
  149.      explictly declare EXTERNAL the GLUT font symbols.  GLUT
  150.      Fortran programmers should explicitly declare EXTERNAL
  151.      the GLUT fonts they use.
  152.  
  153.   o  Neither the MicroUI (mui) or Tubing and Extrusion library (gle)
  154.      have Fortran bindings.
  155.  
  156. INSTALLATION
  157. =============
  158.  
  159. If you want to install the resulting archives into the right system
  160. library directories, do the following:
  161.  
  162.      FOR N32:  cp lib/fglut.n32/libfglut.a /usr/lib32
  163.  
  164.      FOR N64:  cp lib/fglut.n64/libfglut.a /usr/lib64
  165.  
  166. Also, make sure to install the GLUT library implementation versions for
  167. the given object style too.
  168.  
  169. - Mark Kilgard
  170.